ZKIDROnline SDK For Windows

接口开发手册

熵基科技股份有限公司
http://www.zkteco.com

版权声明

非经本公司书面许可,任何单位和个人不得擅自摘抄、复制本书的部分或全部,并不得以任何形式传播。

1. 目录

版权声明1. 目录2. 前言3. 技术规格3.1 平台支持3.2 浏览器支持3.3 硬件支持3.4 技术规格3.5 快速集成4 websocket协议接口说明4.1 通信数据格式定义4.2 ID Card API4.2.1 获取服务信息4.2.2 读取居民身份证信息（方式一）4.2.3 设置主动推送读取的居民身份证信息（方式二）4.2.4 取消主动推送读取的居民身份证信息方式（方式二）4.2.5 读取 SAM 模块编号4.2.6 获取身份证指纹4.2.7 设置当前播放语音4.2.8 onreadcard 事件4.3 IC Card API4.3.1 获取串口号4.3.2 读取 IC 卡的物理卡号4.3.3 读身份证物理卡号4.3.4 读取 IC 卡数据4.3.5 写入 IC 卡数据4.4 Fingerprint API4.4.1 开始采集指纹4.4.2 结束采集4.4.3 oncapture 事件4.4.4 图像比对模板5 http/https 协议接口说明5.1 ID Card API5.1.1 获取服务基本信息5.1.2 读取身份证信息5.1.3 设置语音播放5.1.4 读取 SAM 模块编号5.1.5 获取身份证指纹5.2 Fingerprint API5.2.1 采集指纹图像5.2.2 采集指纹图像和模板5.2.3 指纹图像(原始图)比对模板5.3 IC Card API5.3.1 获取串口号5.3.2 读取 IC 卡物理卡号5.3.3 读身份证物理卡号5.3.4 读取 IC 卡数据5.3.5 写入 IC 卡数据错误码

2. 前言

欢迎使用熵基科技ZKBioOnline SDK, 在使用前请仔细阅读本文档，以便于您能更快地掌握并使用。

3. 技术规格

3.1 平台支持

Windows XP SP3及以上系统

3.2 浏览器支持

高版本谷歌、火狐，IE10及以上IE浏览器等。（注意edge浏览器不支持websocket协议）

3.3 硬件支持

居民身份证读卡器支持列表：

ID100
ID180
ID200
IDM系列

备注：支持串口类型的设备支持读取IC卡（例如：ID200、IDM系列），带指纹模块的支持指纹采集（例如：ID200）

3.4 技术规格

适用于B/S系统

协议	端口号
http	24010
https	24011
websocket	24012

3.5 快速集成

安装

(1) 在客户端双击安装程序“setup.exe”安装sdk。

(2) 按照安装向导完成安装，即可通过http/https/websocket协议访问。

注意：不同协议不支持混合使用

4 websocket协议接口说明

4.1 通信数据格式定义

Web 端与sdk通信采用 JSON 数据格式，各字段区分大小写，定义说明请参考具体接口。

4.2 ID Card API

4.2.1 获取服务信息

请求消息的字段：

功能	获取服务信息
module	common
msgid	自定义消息id
function	info
parameter	无参数，非必要字段

请求消息的示例如下：


{
    "module"    : "common", 
    "msgid"     : "123456789",
    "function"  : "info",
    "parameter" : ""
}

应答消息的字段：

功能	获取服务信息
module	common
msgid	自定义消息id
function	info
ret	0成功，其它失败，具体请参考错误码
data.now	当前请求时间
data.server_version	sdk版本
data.start	sdk服务启动的时间

返回成功如下所示：


x
{
   "data" : {
      "now" : "2020-04-14 14:24:50",
      "server_version" : "2.0.25",
      "start" : "2020-04-14 14:20:40"
   },
   "function" : "info",
   "module" : "common",
   "ret" : 0
}

4.2.2 读取居民身份证信息（方式一）

请求消息的字段说明：

参数名	描述
module	idcard
function	readcard
parameter.dev	设备类型
parameter.repeat	1表示放卡后可以重复读卡，其它表示放一下卡读一次（拿起来，再放下去算一次）
parameter.readtype	1 表示读基本信息，包含证件上的文字信息、相片文件、指纹信息（如果居民身份证上有指纹信息读指纹信息，没有则指纹信息为空） 2 表示只读文字信息和相片信息 3 表示读最新住址信息其他值，则默认是读基本信息。

请求消息示例如下：


xxxxxxxxxx
{
    "module"   : "idcard",  
    "function" : "readcard",
    "parameter": 
    {
        "dev":"1",
        "repeat":"1",
        "readtype":"1"
    }
}

应答消息的字段说明：

参数名	描述
ret	0成功，其它失败，具体请参考错误码
Certificate.Name	姓名
Certificate.Sex	性别
Certificate.Nation	民族（二代证） or 国家（外国人永居证），港澳台居住证无此项
Certificate.NationCode	民族编码（外国人永居证和港澳台居住证无此项）
Certificate.Birthday	出生日期
Certificate.Address	常住地址
Certificate.IDNumber	身份证号/证件号
Certificate.IDIssued	签发机关
Certificate.IssuedData	签发日期
Certificate.ValidDate	有效期截止日期
Certificate.Other	预留字段
Certificate.CardNumber	卡号（暂未使用）
Certificate.PhotoName	保存头像图片的地址
Certificate.Base64Photo	头像图片数据（jpg Base64string）
Certificate.ImageName	证件保存路径
Certificate.Base64Image	证件图片
Certificate.fp_feature1	第一个登记手指指纹特征，若二代证不支持，则返回空
Certificate.fp_feature2	第二个登记手指指纹特征，若二代证不支持，则返回空
Certificate.CardType	卡的类型 1 居民身份证 2 外国人居住证 3 港澳台居住证
Certificate.EnName	英文名，仅外国人居住证才有
Certificate.CnName	中文名，仅外国人居住证才有
Certificate.PassNum	港澳台居住证通行证号
Certificate.VisaTimes	港澳台居住证签发次数/外国人永居证换证次数
Certificate.RelateIDNum	外国人永居证旧版永居证关联号码(2023版外国人永居证才有)
Certificate.OldIDnum	外国人永居证旧版永居证号码(2023版外国人永居证才有)

应答消息示例如下：


x
{
    "ret": 0,
    "Certificate": {
        "Name": "***",  
        "Sex": "女",    
        "Nation": "汉",  
        "NationCode": "1",
        "Birthday": "19950816",      
        "Address": "福建省****号",  
        "IDNumber": "35********67",  
        "IDIssued": "***公安局",     
        "IssuedData": "20170823",   
        "ValidDate": "20270823",    
        "Other": "",
        "CardNumber": "",
        "PhotoName": "F:\\***\\zp.bmp",  
        "Base64Photo": "***",           
        "ImageName": "",
        "Base64Image": "",
        "fp_feature1": "***",   
        "fp_feature2": "***",  
        "CardType": "1",        
        "EnName": "",       
        "CnName": "",       
        "PassNum": "",      
        "VisaTimes": "0",
        "RelateIDNum": "",
        "OldIDnum": "" 
    }
}

备注：读身份证的方式一和方式二，只能使用一种，不支持同时使用

4.2.3 设置主动推送读取的居民身份证信息（方式二）

beginreadcard 方法调用成功后，默认进入读卡状态，每次读取到居民身份证信息都会触发 onreadcard 事件，onreadcard 事件具体参考4.2.9。结束读卡状态需要主动调用 cancelreadcard 方法。

请求消息的字段：

参数名	描述
module	idcard
function	beginreadcard
parameter	无参数，非必要字段

请求消息的示例如下：


xxxxxxxxxx
{
    "module"   : "idcard",  
    "function" : "beginreadcard",
    "parameter": ""
}

应答消息字段说明：

参数名	描述
ret	0成功，其它失败，具体请参考错误码
dev	设备类型
data	结果描述

应答消息示例如下：


xxxxxxxxxx
{
   "data" : "BeginReadCard Succsefull",
   "dev" : 1,
   "ret" : 0
}

4.2.4 取消主动推送读取的居民身份证信息方式（方式二）

请求消息的字段：

参数名	描述
module	idcard
function	cancelreadcard
parameter	无参数，非必要字段

请求消息示例如下：


xxxxxxxxxx
{
    "module"   : "idcard",  
    "function" : "cancelreadcard",
    "parameter": ""
}

应答消息字段说明：

参数名	描述
ret	0成功，其它失败，具体请参考错误码
dev	设备类型
data	结果描述

应答消息示例如下：


xxxxxxxxxx
{
   "data" : "CancelReadCard Succsefull",
   "dev" : 1,
   "ret" : 0
}

4.2.5 读取 SAM 模块编号

请求消息的字段：

参数名	描述
module	idcard
function	getsamid
parameter.dev	设备类型

请求消息示例如下：


xxxxxxxxxx
{
    "module"   : "idcard",  
    "function" : "getsamid",
    "parameter"     : 
    {
        "dev":"1"
    }
}

应答消息字段说明：

参数名	描述
ret	0成功，其它失败，具体请参考错误码
dev	设备类型
data.samid	设备sam模块编号

应答消息示例如下：


xxxxxxxxxx
{
    "data": {
        "samid": "5-3-20171024-8170415-81818637"
    },
    "dev": 1,
    "ret": 0
}

4.2.6 获取身份证指纹

必须通过上述提供的方式一或者方式二成功读取到居民二代身份证，才能通过 getidfp 方法获取居民身份证上保存的指纹信息。

请求消息的字段：

参数名	描述
module	idcard
function	getidfp
parameter.dev	设备类型

请求消息示例如下：


xxxxxxxxxx
{
    "module"   : "idcard",  
    "function" : "getidfp",
    "parameter"     : 
    {
        "dev":"1"
    }
}

应答消息字段说明：

参数名	描述
ret	0成功，其它失败，具体请参考错误码
dev	设备类型
data.feature1	第一个登记手指指纹特征（base64 string）
data.feature2	第二个登记手指指纹特征（base64 string）

应答消息示例如下：


xxxxxxxxxx
{
    "data": {
        "feature1": "***",
        "feature2": "***"
    },
    "dev": 1,
    "ret": 0
}

4.2.7 设置当前播放语音

请求消息的字段：

参数名	描述
module	idcard
function	setvoice
parameter.dev	设备类型
parameter.voicetype	播放的语音类型 0 请放卡 1 读卡成功 2 读卡失败，请重新放卡 3 读卡成功，请核验指纹 4 核验成功 5 核验失败，请重按手指 6 写卡成功 7 写卡失败

请求消息示例如下：


xxxxxxxxxx
{
    "module"   : "idcard",  
    "function" : "setvoice",
    "parameter"     : 
    {
        "dev":"1",
        "voicetype":"1"
    }
}

应答消息字段说明：

参数名	描述
ret	0成功，其它失败，具体请参考错误码
dev	设备类型
data	结果描述

应答消息示例如下：


xxxxxxxxxx
{
    "data": "Set Successful",
    "dev": 1,
    "ret": 0
}

4.2.8 onreadcard 事件

onreadcard事件消息的字段说明：

参数名	描述
ret	0成功，其它失败，具体请参考错误码
event	onreadcard
Certificate.Name	姓名
Certificate.Sex	性别
Certificate.Nation	民族（二代证） or 国家（外国人永居证），港澳台居住证无此项
Certificate.NationCode	民族编码（外国人永居证和港澳台居住证无此项）
Certificate.Birthday	出生日期
Certificate.Address	常住地址
Certificate.IDNumber	身份证号/证件号
Certificate.IDIssued	签发机关
Certificate.IssuedData	签发日期
Certificate.ValidDate	有效期截止日期
Certificate.Other	预留字段
Certificate.CardNumber	卡号（暂未使用）
Certificate.PhotoName	保存头像图片的地址
Certificate.Base64Photo	头像图片数据（jpg Base64string）
Certificate.ImageName	证件保存路径
Certificate.Base64Image	证件图片
Certificate.fp_feature1	第一个登记手指指纹特征，若二代证不支持，则返回空
Certificate.fp_feature2	第二个登记手指指纹特征，若二代证不支持，则返回空
Certificate.CardType	卡的类型 1二代证 2外国人居住证 3港澳台居住证
Certificate.EnName	英文名，仅外国人居住证才有
Certificate.CnName	中文名，仅外国人居住证才有
Certificate.PassNum	港澳台居住证通行证号
Certificate.VisaTimes	港澳台居住证签发次数/外国人永居证换证次数
Certificate.RelateIDNum	外国人永居证旧版永居证关联号码(2023版外国人永居证才有)
Certificate.OldIDnum	外国人永居证旧版永居证号码(2023版外国人永居证才有)

onreadcard 事件返回的消息示例如下：


x
{
    "ret": 0,
    "event": "onreadcard",
    "Certificate": {
        "Name": "***",  
        "Sex": "女",    
        "Nation": "汉",  
        "NationCode": "1",
        "Birthday": "19950816",      
        "Address": "福建省****号",  
        "IDNumber": "35********67",  
        "IDIssued": "***公安局",     
        "IssuedData": "20170823",   
        "ValidDate": "20270823",    
        "Other": "",
        "CardNumber": "",
        "PhotoName": "F:\\***\\zp.bmp",  
        "Base64Photo": "***",           
        "ImageName": "",
        "Base64Image": "",
        "fp_feature1": "***",   
        "fp_feature2": "***",  
        "CardType": "1",        
        "EnName": "",       
        "CnName": "",       
        "PassNum": "",      
        "VisaTimes": "0",
        "RelateIDNum": "",
        "OldIDnum": "" 
    }
}

4.3 IC Card API

4.3.1 获取串口号

请求消息的字段：

参数名	描述
module	iccard
function	getcom
parameter.dev	设备类型

请求消息示例如下：


xxxxxxxxxx
{
    "module"   : "iccard",  
    "function" : "getcom",
    "parameter"     : 
    {
        "dev":"1"
    }
}

应答消息字段说明：

参数名	描述
ret	0成功，其它失败，具体请参考错误码
dev	设备类型
data.name	设备串口号

应答消息返回示例如下：


xxxxxxxxxx
{
    "data": {
        "name": "COM4"
    },
    "dev": 1,
    "ret": 0
}

4.3.2 读取 IC 卡的物理卡号

请求消息的字段：

参数名	描述
module	iccard
function	geticsnr
parameter.dev	设备类型
parameter.iport	设备串口号

请求消息示例如下：


xxxxxxxxxx
{
    "module"   : "iccard",  
    "function" : "geticsnr",
    "parameter"     : 
    {
        "dev":"1",
        "iport":4
    }
}

应答消息字段说明：

参数名	描述
ret	0成功，其它失败，具体请参考错误码
dev	设备类型
data.icsnr	IC卡物理卡号（10进制字符串）

应答消息返回示例如下：


xxxxxxxxxx
{
    "data": {
        "icsnr": "2944354549"
    },
    "dev": 1,
    "ret": 0
}

4.3.3 读身份证物理卡号

请求消息的字段：

参数名	描述
module	iccard
function	getidsnr
parameter.dev	设备类型

请求消息示例如下：


xxxxxxxxxx
{
    "module"   : "iccard",  
    "function" : "getidsnr",
    "parameter"     : 
    {
        "dev":"1",
        "iport":4
    }
}

应答消息字段说明：

参数名	描述
ret	0成功，其它失败，具体请参考错误码
dev	设备类型
data.idsnr	ID卡物理卡号（16进制字符串）

应答消息返回示例如下：


xxxxxxxxxx
{
    "data": {
        "idsnr": "221774858886a47b"
    },
    "dev": 1,
    "ret": 0
}

4.3.4 读取 IC 卡数据

请求消息的字段：

参数名	描述
module	iccard
function	readcard
parameter.dev	设备类型
parameter.iport	设备串口号
parameter.sector	扇区号
parameter.idx	块索引
parameter.key	扇区秘钥（16进制字符串，长度12位）

请求消息示例如下：


xxxxxxxxxx
{
    "module"   : "iccard",  
    "function" : "readcard",
    "parameter": 
    {
        "dev":"1",
        "iport":4,
        "sector":1,
        "idx":2,
        "key":"FFFFFFFFFFFF"
    }
}

应答消息字段说明：

参数名	描述
ret	0成功，其它失败，具体请参考错误码
dev	设备类型
data.ICdata	读取的IC卡块数据（16进制字符串，长度32位）
data.ICid	IC卡物理卡号(int 类型)

应答消息返回示例如下：


xxxxxxxxxx
{
    "ret": 0,
    "dev": 1,
    "data": {
        "ICdata": "12345678900000000000000000000000",
        "ICid": 2944354549
    }
}

4.3.5 写入 IC 卡数据

请求消息的字段：

参数名	描述
module	iccard
function	writecard
parameter.dev	设备类型
parameter.iport	设备串口号
parameter.sector	扇区号
parameter.idx	块索引
parameter.key	扇区秘钥（16进制字符串，长度12位）
parameter.data	要写入扇区块的数据（16进制字符串，长度32位）

请求消息示例如下：


xxxxxxxxxx
{
    "module"   : "iccard",  
    "function" : "writecard",
    "parameter": 
    {
        "dev":"1",
        "iport":4,
        "sector":2,
        "idx":2,
        "key":"FFFFFFFFFFFF",
        "data":"12345678900000000000000000000000"
    }
}

应答消息字段说明：

参数名	描述
ret	0成功，其它失败，具体请参考错误码
dev	设备类型
data.ICid	IC卡物理卡号(int 类型)

应答消息返回示例如下：


xxxxxxxxxx
{
    "ret": 0,
    "dev": 1,
    "data": {
        "ICid": 2944354549
    }
}

4.4 Fingerprint API

4.4.1 开始采集指纹

begincapture 方法调用成功后，默认进入指纹采集状态，每次采集都会触发oncapture 事件，oncapture 事件具体参考4.4.3。需要主动调用 endcapture 方法结束采集状态。

请求消息的字段：

参数名	描述
module	fingerprint
function	begincapture
parameter.dev	设备类型

请求消息示例如下：


xxxxxxxxxx
{
    "module"   : "fingerprint", 
    "function" : "begincapture",
    "parameter"     : 
    {
        "dev":"1"
    }
}

应答消息字段说明：

参数名	描述
ret	0成功，其它失败，具体请参考错误码
dev	设备类型
data	结果描述

应答消息返回示例如下：


xxxxxxxxxx
{
   "data" : "Begin capture.",
   "dev" : 1,
   "ret" : 0
}

4.4.2 结束采集

请求消息的字段：

参数名	描述
module	fingerprint
function	endcapture
parameter.dev	设备类型

请求消息示例如下：


xxxxxxxxxx
{
    "module"   : "fingerprint", 
    "function" : "endcapture",
    "parameter"     : 
    {
        "dev":"1"
    }
}

应答消息字段说明：

参数名	描述
ret	0成功，其它失败，具体请参考错误码
dev	设备类型
data	结果描述

应答消息返回示例如下：


xxxxxxxxxx
{
   "data" : "End capture.",
   "dev" : 1,
   "ret" : 0
}

4.4.3 oncapture 事件

进入采集状态后，每次指纹按在采集器上都会触发oncapture 事件，并返回采集的指纹模板和图片数据。

采集事件返回的字段说明：

参数名	描述
ret	0成功，其它失败，具体请参考错误码
dev	设备类型
event	oncapture
data.feature	指纹模板数据（base64 string）
data.jpgbase64	jpg格式指纹图像（base64 string）
data.rawbase64	原始指纹图像数据（base64 string）

采集事件返回的消息示例如下：


xxxxxxxxxx
{
   "data" : {
      "feature" : "QwH/EgFjRAAA***",
      "jpgbase64" : "/9j/4AAQSk***",
      "rawbase64" : "sQB4cLe1sq***"
   },
   "dev" : 1,
   "event" : "oncapture",
   "ret" : 0
}

4.4.4 图像比对模板

请求消息的字段说明：

参数名	描述
module	fingerprint
function	imagefpmatch
parameter.dev	设备类型
rawbase64	指纹原始图片数据（base64 string）
feature	指纹特征模板（base64 string）

请求消息示例如下：


xxxxxxxxxx
{
    "module"   : "fingerprint", 
    "function" : "imagefpmatch",
    "parameter"     : 
    {
        "dev":"1",
        "rawbase64":"...",
        "feature":"..."
    }
}

应答消息字段说明：

参数名	描述
ret	0成功，其它失败，具体请参考错误码
dev	设备类型
data.score	比对返回的分数

应答消息返回示例如下：


xxxxxxxxxx
{
    "data": {
        "score": 62
    },
    "dev": 1,
    "ret": 0
}

5 http/https 协议接口说明

5.1 ID Card API

5.1.1 获取服务基本信息

请求方法：


xxxxxxxxxx
HTTP GET
    http://127.0.0.1:24010/ZKIDROnline/info
OR
    https://127.0.0.1:24011/ZKIDROnline/info

返回消息的字段说明：

功能	获取服务信息
ret	0成功，其它失败，具体请参考错误码
data.now	当前请求时间
data.server_version	sdk版本
data.start	sdk服务启动的时间

返回消息示例如下：


xxxxxxxxxx
{
    "ret":0,
    "data": 
    {
        "server_version": "2.0.26",
        "start": "2020-07-23 17:03:23",
        "now": "2020-07-23 17:04:56"
    }
}

5.1.2 读取身份证信息

请求方法：


xxxxxxxxxx
HTTP GET
    http://127.0.0.1:24010/ZKIDROnline/ScanReadIdCardInfo?OP-DEV=1&CMD-URL=4&REPEAT=1&READTYPE=1&TIMEOUT=4
OR
    https://127.0.0.1:24011/ZKIDROnline/ScanReadIdCardInfo?OP-DEV=1&CMD-URL=4&REPEAT=1&READTYPE=1&TIMEOUT=4

请求方法中的参数说明：

参数名	参数类型	描述
OP-DEV	int	设备类型
CMD-URL	int	4 表示读取身份证信息
REPEAT	int	1表示放卡后可以重复读卡，其它表示放一下卡读一次（拿起来，再放下去算一次）
READTYPE	int	1 表示读基本信息，包含证件上的文字信息、相片文件、指纹信息（如果居民身份证上有指纹信息读指纹信息，没有则指纹信息为空） 2 表示只读文字信息和相片信息 3 表示读最新住址信息其他值，则默认是读基本信息。
TIMEOUT	int	读卡的超时时间（以s为单位）

返回消息的字段说明：

参数名	描述
ret	0成功，其它失败，具体请参考错误码
Certificate.Name	姓名
Certificate.Sex	性别
Certificate.Nation	民族（二代证） or 国家（外国人永居证），港澳台居住证无此项
Certificate.NationCode	民族编码（外国人永居证和港澳台居住证无此项）
Certificate.Birthday	出生日期
Certificate.Address	常住地址
Certificate.IDNumber	身份证号/证件号
Certificate.IDIssued	签发机关
Certificate.IssuedData	签发日期
Certificate.ValidDate	有效期截止日期
Certificate.Other	预留字段
Certificate.CardNumber	卡号（暂未使用）
Certificate.PhotoName	保存头像图片的地址
Certificate.Base64Photo	头像图片数据（jpg Base64string）
Certificate.ImageName	证件保存路径
Certificate.Base64Image	证件图片
Certificate.fp_feature1	第一个登记手指指纹特征，若二代证不支持，则返回空
Certificate.fp_feature2	第二个登记手指指纹特征，若二代证不支持，则返回空
Certificate.CardType	卡的类型 1居民身份证 2外国人居住证 3港澳台居住证
Certificate.EnName	英文名，仅外国人居住证才有
Certificate.CnName	中文名，仅外国人居住证才有
Certificate.PassNum	港澳台居住证通行证号
Certificate.VisaTimes	港澳台居住证签发次数/外国人永居证换证次数
Certificate.RelateIDNum	外国人永居证旧版永居证关联号码(2023版外国人永居证才有)
Certificate.OldIDnum	外国人永居证旧版永居证号码(2023版外国人永居证才有)

返回消息示例如下：


xxxxxxxxxx
{
    "ret": 0,
    "Certificate":
    {
        "Name": "***",
        "Sex": "男",
        "Nation": "汉",
        "NationCode": "1",
        "Birthday": "19940411",
        "Address": "福建省*******号",
        "IDNumber": "35*************",
        "IDIssued": "***公安局",
        "IssuedData": "20110310",
        "ValidDate": "20210310",
        "Other": "",
        "CardNumber": "",
        "PhotoName": "F:\\***\\zp.bmp",
        "Base64Photo": "/9j/4..",
        "ImageName": "",
        "Base64Image": "(null)",
        "fp_feature1": "",
        "fp_feature2": "",
        "CardType": "1",
        "EnName": "",
        "CnName": "",
        "PassNum": "",
        "VisaTimes": "0"
        "RelateIDNum": "",
        "OldIDnum": "" 
    }
}

5.1.3 设置语音播放

请求方法：


xxxxxxxxxx
HTTP GET
    http://127.0.0.1:24010/ZKIDROnline/ScanReadIdCardInfo?OP-DEV=1&CMD-URL=16&VoiceType=0
OR
    https://127.0.0.1:24011/ZKIDROnline/ScanReadIdCardInfo?OP-DEV=1&CMD-URL=16&VoiceType=0

请求方法中的参数说明：

参数名	参数类型	描述
OP-DEV	int	设备类型
CMD-URL	int	16 表示设置语音播放
VoiceType	int	语音类型有(VoiceType的值)： 0 请放卡 1 读卡成功 2 读卡失败，请重新放卡 3 读卡成功，请核验指纹 4 核验成功 5 核验失败，请重按手指 6 写卡成功 7 写卡失败

返回的消息字段：

参数名	参数类型	描述
ret	int	0成功，其它失败，具体请参考错误码
dev	int	设备类型
data	string	提示

返回消息示例如下：


xxxxxxxxxx
{
    "ret":0,
    "dev":1,
    "data":"set successful"
}

5.1.4 读取 SAM 模块编号

请求方法：


xxxxxxxxxx
HTTP GET
    http://127.0.0.1:24010/ZKIDROnline/ScanReadIdCardInfo?OP-DEV=1&CMD-URL=11
OR
    https://127.0.0.1:24011/ZKIDROnline/ScanReadIdCardInfo?OP-DEV=1&CMD-URL=11

请求方法中的参数说明：

参数名	参数类型	描述
OP-DEV	int	设备类型
CMD-URL	int	11 表示读取sam模块编号

返回的消息字段：

参数名	参数类型	描述
ret	int	0成功，其它失败，具体请参考错误码
dev	int	设备类型
data.samid	string	sam 模块编号

返回消息示例如下：


xxxxxxxxxx
{
    "ret":0,
    "dev":1,
    "data":{"samid":"5-3-20171024-8170397-2614984769"}
}

5.1.5 获取身份证指纹

必须通过5.1.2介绍的 /ZKIDROnline/ScanReadIdCardInfo?OP-DEV=1&CMD-URL=4&REPEAT=1&READTYPE=1 方法成功读取到居民二代身份证，才能通过当前方法获取居民身份证上保存的指纹信息。

请求方法：


xxxxxxxxxx
HTTP GET
    http://127.0.0.1:24010/ZKIDROnline/ScanReadIdCardInfo?OP-DEV=1&CMD-URL=14
OR
    https://127.0.0.1:24011/ZKIDROnline/ScanReadIdCardInfo?OP-DEV=1&CMD-URL=14

请求方法中的参数说明：

参数名	参数类型	描述
OP-DEV	int	设备类型
CMD-URL	int	14 表示获取身份证指纹特征

返回的消息字段：

参数名	参数类型	描述
ret	int	0成功，其它失败，具体请参考错误码
dev	int	设备类型
data.feature1	base64 string	第一个登记手指指纹特征
data.feature2	base64 string	第二个登记手指指纹特征

返回消息示例如下：


xxxxxxxxxx
{
    "ret":0,
    "dev":1,
    "data":{
        "feature1":"QwGUEg...",
        "feature2":"QwGUEg..."
    }
}

5.2 Fingerprint API

5.2.1 采集指纹图像

请求方法：


xxxxxxxxxx
HTTP GET
    http://127.0.0.1:24010/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=1
OR
    https://127.0.0.1:24011/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=1

请求方法中的参数说明：

参数名	参数类型	描述
OP-DEV	int	设备类型
CMD-URL	int	1表示采集指纹图像
TIMEOUT	int	设置采集超时时间(单位 s),如果没有传入该参数，默认采集时间为2s

返回的消息字段：

参数名	参数类型	描述
ret	int	0成功，其它失败，具体请参考错误码
dev	int	设备类型
data.rawBase64	base64 string	原始指纹图像
data.jpgBase64	base64 string	jpg格式指纹图像

返回消息示例如下：


xxxxxxxxxx
{
    "ret":0,
    "dev":1,
    "data":{
        "rawBase64":"z8XL...",
        "jpgBase64":"/9j/..."
    }
}

5.2.2 采集指纹图像和模板

请求方法：


xxxxxxxxxx
HTTP GET
    http://127.0.0.1:24010/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=2
OR
    https://127.0.0.1:24011/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=2

请求方法中的参数说明：

参数名	参数类型	描述
OP-DEV	int	设备类型
CMD-URL	int	2表示采集指纹图像和指纹模板
TIMEOUT	int	设置采集超时时间(单位 s), 如果没有传入该参数，默认采集时间为2s

返回的消息字段：

参数名	参数类型	描述
ret	int	0成功，其它失败，具体请参考错误码
dev	int	设备类型
data.feature	base64 string	指纹特征
data.rawBase64	base64 string	原始指纹图像
data.jpgBase64	base64 string	jpg格式指纹图像

返回消息示例如下：


xxxxxxxxxx
{
    "ret":0,
    "dev":1,
    "data":{
        "feature":"QwH/Eg...",
        "rawBase64":"yr2x...",
        "jpgBase64":"/9j/..."
    }
}

5.2.3 指纹图像(原始图)比对模板

请求方法：


xxxxxxxxxx
HTTP POST
    http://127.0.0.1:24010/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=3
OR
    https://127.0.0.1:24011/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=3
POST数据如下：
    {
        "rawBase64":"Base64 String",        
        "feature":"Base64 String"           
    }

请求方法中的参数说明：

参数名	参数类型	描述
OP-DEV	int	设备类型
CMD-URL	int	3表示指纹原始图像比对指纹模板

POST 的数据格式参数：

参数名	参数类型	描述
rawBase64	base64 string	原始指纹图像
feature	base64 string	指纹模板

POST的数据示例如下：


xxxxxxxxxx
{
    "rawBase64":"Base64 String", 
    "feature":"Base64 String"      
}

返回的消息字段：

参数名	参数类型	描述
ret	int	0成功，其它失败，具体请参考错误码
data.score	int	比对分数

返回消息示例如下：


xxxxxxxxxx
{
    "ret":0,
    "data":
    {
        "score": 80
    }
}

5.3 IC Card API

5.3.1 获取串口号

请求方法：


xxxxxxxxxx
HTTP GET
    http://127.0.0.1:24010/ZKIDROnline/MFCard?OP-DEV=1&CMD-URL=5
OR
    https://127.0.0.1:24011/ZKIDROnline/MFCard?OP-DEV=1&CMD-URL=5

请求方法中的参数说明：

参数名	参数类型	描述
OP-DEV	int	设备类型
CMD-URL	int	5 表示获取串口号

返回的消息字段：

参数名	参数类型	描述
ret	int	0成功，其它失败，具体请参考错误码
dev	int	设备类型
data.name	string	设备com端口

返回消息示例如下：


xxxxxxxxxx
{
    "ret":0,
    "dev":1,
    "data":{
        "name":"COM5"
    }
}

5.3.2 读取 IC 卡物理卡号

请求方法：


xxxxxxxxxx
HTTP GET
    http://127.0.0.1:24010/ZKIDROnline/MFCard?OP-DEV=1&CMD-URL=1&iPort=5
OR
    https://127.0.0.1:24011/ZKIDROnline/MFCard?OP-DEV=1&CMD-URL=1&iPort=5

请求方法中的参数说明：

参数名	参数类型	描述
OP-DEV	int	设备类型
CMD-URL	int	1表示读取IC卡物理卡号
iPort	int	要打开的端口号

返回的消息字段：

参数名	参数类型	描述
ret	int	0成功，其它失败，具体请参考错误码
dev	int	设备类型
data.ICSnr	string	IC卡物理卡号（10进制字符串）

返回消息示例如下：


xxxxxxxxxx
{
    "ret":0,
    "dev":1,
    "data": {
        "ICSnr":"2944354549"
    }
}

5.3.3 读身份证物理卡号

请求方法：


xxxxxxxxxx
HTTP GET
    http://127.0.0.1:24010/ZKIDROnline/MFCard?OP-DEV=1&CMD-URL=2&iPort=5
OR
    https://127.0.0.1:24011/ZKIDROnline/MFCard?OP-DEV=1&CMD-URL=2&iPort=5

请求方法中的参数说明：

参数名	参数类型	描述
OP-DEV	int	设备类型
CMD-URL	int	2 表示读取身份证物理卡号
iPort	int	要打开的端口号

返回的消息字段：

参数名	参数类型	描述
ret	int	0成功，其它失败，具体请参考错误码
dev	int	设备类型
data.IDSnr	string	ID卡物理卡号（16进制字符串）

返回消息示例如下：


xxxxxxxxxx
{
    "ret":0,
    "dev":1,
    "data": {
        "IDSnr":"10d5d000e508101b"
    }
}

5.3.4 读取 IC 卡数据

请求方法：


xxxxxxxxxx
HTTP GET
    http://127.0.0.1:24010/ZKIDROnline/MFCard?OP-DEV=1&CMD-URL=3&iPort=5&Sector=0&Idx=2&Key=FFFFFFFFFFFF
OR
    https://127.0.0.1:24011/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=3&iPort=5&Sector=0&Idx=2&Key=FFFFFFFFFFFF

请求方法中的参数说明：

参数名	参数类型	描述
OP-DEV	int	设备类型
CMD-URL	int	3 获取IC卡数据
iPort	int	要打开的端口号
Sector	int	扇区号
Idx	int	块索引
Key	string	扇区密钥(16进制字符串，长度12)

返回的消息字段：

参数名	参数类型	描述
ret	int	0成功，其它失败，具体请参考错误码
dev	int	设备类型
data.ICdata	string	IC卡数据(16进制字符串，长度32)
data.ICid	int	IC卡物理卡号

返回消息示例如下：


xxxxxxxxxx
{
    "ret":0,
    "dev":1,
    "data": {
        "ICdata":"*******",
        "ICid":2944354549
    }
}

5.3.5 写入 IC 卡数据

请求方法：


xxxxxxxxxx
HTTP GET
    http://127.0.0.1:24010/ZKIDROnline/MFCard?OP-DEV=1&CMD-URL=4&iPort=5&Sector=0&Idx=2&Key=FFFFFFFFFFFF&Data=*****
OR
    https://127.0.0.1:24011/ZKIDROnline/IDFP?OP-DEV=1&CMD-URL=4&iPort=5&Sector=0&Idx=2&Key=FFFFFFFFFFFF&Data=*****

请求方法中的参数说明：

参数名	参数类型	描述
OP-DEV	int	设备类型
CMD-URL	int	4表示设置IC卡数据
iPort	int	要打开的端口号
Sector	int	扇区号
Idx	int	块索引
Key	string	扇区密钥(16进制字符串，长度12)
Data	string	写卡的数据(16进制字符串，长度32)

返回的消息字段：

参数名	参数类型	描述
ret	int	0成功，其它失败，具体请参考错误码
dev	int	错误描述
data.ICid	int	IC 卡物理卡号

返回消息示例如下：


xxxxxxxxxx
{
    "ret":0,
    "dev":1,
    "data": {
        "ICid": 2944354549
    }
}

错误码

错误代码	说明
0	成功
1	端口打开失败
2	数据传输超时
3	设置超时时间失败
4	设备忙打开失败
6	接口地址参数有误
10	没有找到卡
11	读卡失败
20	自检失败
30	其他错误
40	相片解码失败
100	超时
200	获取照片Base64失败
201	操作失败
202	IC卡参数出错
-1	获取指纹失败
-100	ID/IC卡模块加载失败
203	加载指纹采集库失败
204	加载指纹的算法库失败
205	初始化算库失败
206	初始化采集器失败
207	找不到二代证采集器
208	打开采集器失败
209	采集器采集图像失败
210	采集模板失败
211	比对模板无效
212	传入的JSON格式转换有误
213	比对失败
214	采集器采集图像超时
215	播报的语音类型不支持
216	设置播报语音失败
其他	未知错误

版权声明

1. 目录

2. 前言

3. 技术规格

3.1 平台支持

3.2 浏览器支持

3.3 硬件支持

3.4 技术规格

3.5 快速集成

4 websocket协议接口说明

4.1 通信数据格式定义

4.2 ID Card API

4.2.1 获取服务信息

4.2.2 读取居民身份证信息 （方式一）

4.2.3 设置主动推送读取的居民身份证信息 （方式二）

4.2.4 取消主动推送读取的居民身份证信息方式 （方式二）

4.2.5 读取 SAM 模块编号

4.2.6 获取身份证指纹

4.2.7 设置当前播放语音

4.2.8 onreadcard 事件

4.3 IC Card API

4.3.1 获取串口号

4.3.2 读取 IC 卡的物理卡号

4.3.3 读身份证物理卡号

4.3.4 读取 IC 卡数据

4.3.5 写入 IC 卡数据

4.4 Fingerprint API

4.4.1 开始采集指纹

4.4.2 结束采集

4.4.3 oncapture 事件

4.4.4 图像比对模板

5 http/https 协议接口说明

5.1 ID Card API

5.1.1 获取服务基本信息

5.1.2 读取身份证信息

5.1.3 设置语音播放

5.1.4 读取 SAM 模块编号

5.1.5 获取身份证指纹

5.2 Fingerprint API

5.2.1 采集指纹图像

5.2.2 采集指纹图像和模板

5.2.3 指纹图像(原始图)比对模板

5.3 IC Card API

5.3.1 获取串口号

5.3.2 读取 IC 卡物理卡号

5.3.3 读身份证物理卡号

5.3.4 读取 IC 卡数据

5.3.5 写入 IC 卡数据

错误码

4.2.2 读取居民身份证信息（方式一）

4.2.3 设置主动推送读取的居民身份证信息（方式二）

4.2.4 取消主动推送读取的居民身份证信息方式（方式二）